Third-party plug-ins for ContactsLaw are installed, updated and removed via a component known as the plug-in manager. This is the preferred mechanism for plug-ins to be deployed to users.
Plug-in life cycle
Although it is possible to reload plug-ins at any time, ContactsLaw can only install, update or remove plug-ins during startup. Therefore, when a user clicks on a link to install a new plug-in, the action is deferred and the user receives a prompt to restart ContactsLaw to complete the operation.
On startup, the plug-in manager will:
- Uninstall any plug-ins pending removal.
- If an Internet connection is available, checks for (and automatically installs) updates to all installed plug-ins and installs any plug-ins pending installation. This occurs in no particular order, therefore plug-in developers should not make assumptions about the installation order of any two plug-ins.
Note: Plug-ins are managed on a per-machine basis. Any plug-ins installed by a user will be automatically available to all other users of the same computer.
Manifest files
The plug-in manager uses XML-based manifest files to identify third-party plug-ins and download the installation files. The installation package must be a ZIP file. Vendors will typically place both the manifest file and installation package on a web server.
Each plug-in must have a unique identifier, given as a GUID. ContactsLaw will use this value to differentiate the plug-in from others that may be installed.
The manifest includes the number of the latest version (i.e. the version pointed to by the package URL). You must increment this number when publishing an updated version.
Below is an example of the structure of the document:
<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns="http://download.overtech.com.au/schemas/PluginManifest.xsd" guid="{AC622116-EF28-413D-9F90-23504DB9DC20}">
<name>Name of the plug-in</name>
<version>1.0.0.0</version>
<packageUrl>http://myserver/path/package.zip</packageUrl>
</plugin> |
Advanced features
Occasionally, updates to ContactsLaw include breaking changes that may affect plug-ins designed for older versions. If you wish to restrict installation of a plug-in based on the installed version of ContactsLaw, include the optional <compatibility> element and specify minimum/maximum version numbers. If you maintain multiple versions, you can include the <alternateManifestUrl> element which points to a separate plug-in manifest that is downloaded if the compatibility requirements are not met.
If the URL of a plug-in manifest changes, you can direct ContactsLaw to the new URL by including the <manifestUrl> element. This must be present in the manifest at the original location, so for a time you may need to continue to operate the old location.
Installation
To install a plug-in, users must click on a vendor-supplied hyperlink which instructs ContactsLaw to perform the installation.
e.g. contactslaw://-/installplugin?uri=http://myserver/path/plugin.xml
(The URI above points to the manifest file for the plug-in.)
ContactsLaw will always install the latest version of the plug-in available (regardless of when the user restarts the application).
Any existing files in the target directory will be overwritten (hence all plug-in files except shared assemblies must be uniquely named). To avoid collisions, plug-ins may create subdirectories, however the main DLL must be placed in the top-level directory.
Shared assemblies
The plug-in manager will not maintain multiple versions of shared assemblies. As such, you should not reference specific versions of strong-named assemblies. Binding redirections can be used to mitigate versioning issues.
Updates
A plug-in will be updated if the version number in the manifest file is higher than the installed version. The URL to the installation package may change between versions, however the manifest URL does not change (see Advanced features above for relocation procedure).
The update procedure is equivalent to uninstalling and reinstalling the plug-in; any files installed by the previous version are deleted, hence plug-ins are not permitted to store persistent data in the installation folder (instead, they should use either user-scoped settings or practice-level settings managed by ContactsLaw).
Uninstallation
Uninstalling a plug-in removes all files that were previously installed, except those which are still required by other plug-ins.
Auto-installed plug-ins
System administrators can specify, through the DDM manager utility, a set of plug-ins that will be automatically installed for all users. Users are not prevented from uninstalling plug-ins on this list, however they will be automatically reinstalled the next time the application starts. If the auto-install list is modified, redundant plug-ins will not be uninstalled automatically.
The list must be specified in XML format. Below is an example of the structure of the document:
<plugins>
<plugin guid="ED2A37B8-E674-4CEE-9364-040DCFA3D0A8">
<manifestLocation>http://myserver/path/plugin.xml</manifestLocation>
<name>Name of the plug-in</name>
</plugin>
<plugin guid="C4EED4CB-401F-485E-9BCA-FDFE2B10EEAA">
<manifestLocation>http://anotherserver/anotherpath/plugin.xml</manifestLocation>
<name>Another plug-in</name>
</plugin>
</plugins> |